F R E E P R I N T E R 
                         Documentation for Version 2.7
 
                         by Elliot Lifson [72767,3352]
                                NINCOMPUTE LTD.
 
This program is presented as a machine language alternative to the "PRINT.LUTUS" program elsewhere. It was designed to work as a text printer to accompany Paul Lutus' FREEWRITER program.  While performing the functions of the PRINT.LUTUS program, it also supports many of the APPLEWRITER imbedded print commands, which adds to its usefulness. In addition, it can be used as a quick screen or printer dump for sequential text files (which was my original intent when writing it, oddly enough. It grew, sort of!)
 
This is a revision to add some enhancements and features based on requests of
people using the earlier program. Specifically, there is now a "Line
Interval" parameter, used for skipping lines. The speed of the scrolling
display can be varied while scrolling (a feature found in ASCII Express which
is too handy to ignore). The BASIC.SYSTEM interface is more bullet proof. The
title display is only done once, so that you can catalog a directory and
still see the filenames while typing one in. Finally, I've traded the CTRL-C
key for the Escape Key to abort the program, as it appears to be more of a
standard. 
 
The program resides between $8000 and $8FCF, and uses $9000-$90FF as a
utility buffer. There are two buffer areas into which text is loaded before
it is formatted and displayed. The buffers are contiguous, and as FREEPRINTER
is supplied they occupy $F00-$7FFF; however, this space can be reduced to one
as small as $300 bytes. Thus, FREEPRINTER could conceivably be co-resident
with a rather large Applesoft program, as long as HIMEM is set correctly.
 
 
                             TO USE FREEPRINTER

The binary file FREEPRINTER is not a SYSTEM file and should be BRUN from the Applesoft prompt. (The "-" DASH command may be used, of course.)
 
BRUNning the program will initialize the Ampersand Vector, and start the
program. After exiting, an Ampersand (&) from the keyboard will restart the
program for further passes, without modifying the printer parameters you have
established. All characters after the Ampersand will be ignored, except for
an uppercase "Q" which will restore the original contents of the Ampersand
Vector and terminate the program.
 
The program will prompt you for the name of a textfile. Normal ProDOS
protocol is used here; the prefix will be retrieved if you don't supply one,
and created from the default slot & drive if ProDOS doesn't have one stored
away. A null entry will return you to Applesoft. As a time-saver for repeated
use, entering an equal sign ("=") instead of a filename will cause the
program to use the last filename you entered, recovered from its buffer at
$9000. The program will test the validity of a stored pathname, and if the
pathname is not valid you will have to re-enter the pathname from scratch.
 
Note that the program checks to make sure that your filename refers to a text
file. Currently, only normal TXT files (ID byte = $04) are supported, but you
may add whatever file types you like to this list. (See the section on
CUSTOMIZING, below.)
 
The program then loads your text file (or as much of it as it can fit into
its main buffer), and displays the default printer parameters. We will
discuss the parameters and how to set them in the section on PARAMETERS,
below; however, to accept the parameters, press the <RETURN> key. 
 
You are then given a final chance to change your mind. Press a "Y" to
indicate that all is okay. Then you are given a few on-screen reminders: a
keypress will freeze and restart the display, and the ESC key will abort the
listing. If you are not printing (printing is defined as output to a slot
other than 0 or 3), provision is made to slow the rate of the screen dump;
pressing the "." key speeds up the display, while pressing "," slows it down.
At boot-time, FREEPRINTER is set to screen-dump somewhat slower than full
speed.
 
After the file has been dumped, a press of any key will return you to
Applesoft, with 80-column firmware off and all files closed.
 
 
 
                              PARAMETERS OVERVIEW

The parameters are pretty straight forward. The default is my idea of a quick
screen dump of a textfile: Left margin = 0, Right margin = 78, Output to Slot
3, and Page Interval = 0.
 
To change a parameter from the menu, merely type in its two-letter mnemonic
followed by an argument, if required. All numeric arguments are treated
modulo 256; the only time a negative argument is permitted is with the
Paragraph Margin (PM) command. Here, a negative argument less than -128 will
give you strange and wonderful results, but probably not the value you
wanted. 
 
FREEPRINTER uses the 2-letter mnemonics that it does because they correspond
to the traditional APPLEWRITER mnemonics. This lets FREEPRINTER work with
APPLEWRITER documents which may already exist, (perhaps they've been
converted from DOS 3.3) and greatly expands the usefulness of both this
program and the FREEWRITER program. To imbed a printer command in your
document, merely start a paragraph with a period followed by the mnemonic and
argument. Invalid commands and/or anything on the line following a valid
command will be ignored.
 
 
                                   PARAMETERS

With the exception of the Paragraph Margin parameter below, all parameters
have absolute value limits of 0 to 255, as they are all 1 byte values. The
Paragraph Margin is a one byte signed value, so it may range from -128 to
+127.
 
LEFT MARGIN (LM) defines the column in which the line's first character is
printed. Practically speaking it won't be greater than 60 or so, and must be
set so the total of LM and PM is at most 5 less than RM, or you will generate
an error. (LM + PM + 5 <= RM)
 
RIGHT MARGIN (RM) defines the last possible column into which the line may
extend. If the margin comes in the middle of a word, the word is moved to the
beginning of the next line. RM must be at least 5 more than LM + PM; this
provides a minimum line length of 5 characters. Please note that if you are
dumping text to screen, a RM of 39 or more (on a 40-column screen) or 79 or
more (on an 80-column screen) will generate an extra carriage return if the
number of characters on that line is 40 or more (or 80 or more), due to the
Monitor routine's automatic scrolling action; therefore, use instead a RM of
38 (or 78) at these times.
 
(If that seems confusing, remember that FREEPRINTER, like APPLEWRITER, starts
counting screen columns with 0; a left margin of zero and a right margin of
79 implies that the first character is printed in the first column (column
zero), and the last character in the 80th column (column 79). The auto-scroll
is triggered when printing a character in column 79; so to avoid it, set RM
so the last column printed to is column 78.)
 
PARAGRAPH MARGIN (PM) is the number of spaces added to or subtracted from LM
at the beginning of a new paragraph. (i.e. after a carriage return, or as the
first line of a new document.) PM can be positive or negative; if the sum of
LM and PM equals a number less than zero, printing starts at the left edge of
the page (column zero). As stated above, if LM + PM + 5 exceeds RM, an error
will be generated. The Paragraph Margin is only executed if text is
Left-Justified, (See PRINT MODES, below), but the validity of the value is
always error-checked.
 
EXAMPLE: With a LM of five and PM of 0, each line will begin at column 5,
whether it begins a paragraph or not. With LM=5 and PM=5, the first line of
each paragraph begins at column 10 (5+5=10), with subsequent lines starting
at column 5. If PM is now set to -4, the first line of each paragraph will
start at column 1 (5+(-4)=1), with subsequent lines starting at column 5.
Finally, if pm is set to -6, an error will NOT be generated; the first line
of the paragraph will merely be printed at column zero. (Again, please note
that because the first column is numbered as column zero, column 5 is
actually the 6th column, column 10 is actually the 11th column, etc.) 
 
LINE INTERVAL (LI) is the number of extra lines skipped after each line is
printed. LM=0 implies single spacing, LM=1 implies double spacing, etc.
 
OUTPUT TO WHAT SLOT (Printer Destination, or PD in the APPLEWRITER
convention) is as you would expect it; Slot 0 is the 40-column screen, 3 is
normally for 80-column screens. Output to a slot number greater than 7
generates an error.
 
NOTE: This program is specifically  written for an Apple compatible 80-column
card in the AUX slot; (that is, it prints an ASCII CTRL-U through COUT to
turn off the card.) It should do no harm if the program is run entirely in
80-column mode, if your card is not compatible. Also, I'll be happy to supply
the source code for this program if anyone would like to modify it for their
own particular 80-column card.
 
N.B. If output is directed to Slot 0 or 3, the program assumes a screen dump
is taking place; if output goes to any other slot, the program assumes it is
feeding a printer. This determines the outcome of certain decisions made at
run-time.
 
A PAGE INTERVAL (PI) of zero forces continuous output; NO PAGE FORMATTING
TAKES PLACE. A non-zero value here defines how many lines there are on your
page (normally 66 for a standard 8-1/2 by 11 page, or 72 lines for 8-1/2 by
14). If PI is zero, the Page Length (PL), Top Margin (TM), and Top Line (TL
commands will do nothing when dumping text, no matter what they are set for,
and their values are not checked for validity. Also, an imbedded Form Feed
(FF) command will have no effect.
 
PRINTED LINES PER PAGE (PL) determines how many lines of text to print and,
by extension, how many blank lines at the top and bottom of the page. On
every page, half of the difference of PI - PL lines are skipped at the top,
PL lines of text are printed, and half the difference of PI - PL lines are
skipped at the bottom. This will serve to center the number of printed lines
on the page. With this in mind, FREEPRINTER will work best if you position
your printer to start printing at the top line of the first page.
 
EXAMPLE: A PI of 66 and a PL of 60 will first print 3 blank lines at the top
of the page, then a repetition consisting of a sequence of 60 text lines
followed by 6 blank lines (3 for the bottom margin of the current page, 3 for
the top margin of the next page), over and over, until the document is
completed.
 
(NOTE: FREEPRINTER may be modified to skip past the first page's top margin
lines; see the MODIFICATIONS section below.)
 
PL must be set no lower than 3, and no greater than PI, or an error will be
generated.
 
SPACES AFTER TOP LINE (TM, or Top Margin in the APPLEWRITER convention)
provides control over how many lines to skip after the Header line is
printed. (The Header Line, if used, is the first text line printed after the
top-of-form spaces described above in the PL section.) This value may not
exceed PL - 2, or an error will occur. (This guarantees at least one text
line printed per page.) If there is no Header line entered, the TM value is
irrelevant and is not checked for validity.
 
In operation, the Header Line + Spaces after top line + remainder of text on
the page is centered between the top and bottom margins. To expand on the
example above, with a PI of 66 and a PL of 60, adding a TM of 2 with a header
line, each page will consist of three blank lines as margin, then the header,
then two more blank lines, 57 lines of text, and finally three more blank
lines as margin.
 
SINGLE PAGE (SP) lets you use a single sheet printer by prompting you to
insert a new sheet of paper after each page is completed. A zero value
defeats this feature, and a non-zero value enables it. A non-zero value
entered will always be displayed as "1".
 
SCREEN FORMAT (SF, not an APPLEWRITER command) permits you the option of
letting your screen dump ignore or implement imbedded text commands. If the
value is 0, your textfile is dumped to the screen as-is; only the formatting
commands you entered from the menu are in effect. If SF is non-zero, imbedded
commands are implemented, and you can see their affect. Remember though, this
command only affects SCREEN dumps; Printer dumps always do the imbedded
commands. As in the Single Page command, a non-zero SF value is always
displayed as "1".
 
PRINT MODE (LJ/RJ/CJ/FJ): These four commands determine the formatting of
your document. Left Justification (LJ) means all lines start at the left
margin, leaving you a ragged right margin. Right Justification (RJ) means
each line's last character is printed at the right margin, with a ragged left
margin. Center Justification (CJ) means all lines will be centered between
left and right margins, leaving ragged ends on both sides. Full Justification
(FJ) forces extra spaces to be inserted between words to make each line start
at the left margin and end at the right margin. If the line ends in a
carriage return, it is left justified. Remember that Paragraph Margin only
operates in LJ mode.
 
NOTE: If your document has imbedded printer control characters or escape
sequences, a screen dump will display them as inverse characters, but a
printer dump will faithfully transmit them to the printer. Unlike APPLEWRITER
however, when dumping to printer, non-printing characters are taken into
account when justification calculations are made. Therefore, lines containing
underlining commands, for example, will center correctly without need for
special margin settings. As supplied, FREEPRINTER will justify correctly for
all imbedded control characters, and for escape sequences consisting of the
Escape Character followed by one non-control character. (Provision is made
for the user to modify this to the Escape Character followed by two or three
non-control characters; see the section on CUSTOMIZING, below.)
 
The HEADER LINE (TOP LINE, or TL in the APPLEWRITER convention) can be any
character string you would like printed at the top of each page. If the "#"
character is imbedded, the page number will be substituted when the document
is printed. The page number, too, is a one byte value, so after page 255, the
next page is 0. The header line can be centered between LM and RM, or printed
at the left or right margin, depending upon the number of leading asterisks.
One or no leading asterisks forces a left-justified Header line; 2 leading
asterisks causes a centered Header line; 3 or more causes a right-justified
Header line.
 
EXAMPLE: You have a LM of 5 and a RM of 75; you would like the header to say
"PAGE #". Entering TLPAGE # or TL*PAGE # will print the header at column 5;
entering tl**PAGE # will center it between column 5 and column 75  and
TL***PAGE # will print it so the last character is in column 75. You may
optionally insert any number of spaces after the mnemonic, intermixed with
the asterisks, or before the first letter of actual Header text, and they
will be ignored. Unlike APPLEWRITER, you may not have separate texts
justified left, center, and right at the same time; also, unlike APPLEWRITER,
a trailing asterisk will be printed as part of the text.   If the length of
the Header Line (after "#" has been converted to a page number) exceeds
RM-LM, the Header Line will be left-justified despite the number of
asterisks, and it will not wrap at RM; it will continue until the output
device wraps it.
 
If you wish to remove a Header Line entry without replacing it, enter
TL<RETURN>.
 
The FORM-FEED (FF) command doesn't appear on the menu, but is supported as
an imbedded command. This forces the remainder of the current page to be
skipped, and printing resumed at the top of the next page.
 
 
 
                                 ERROR-TRAPPING                              

As noted above, bad combinations of parameters will generate an error
message. If the bad parameters are entered from the menu, you will not be
able to exit the menu routine until the errors have been reconciled. However,
this doesn't prevent errors caused by bad imbedded commands. If an error is
generated while a screen dump takes place, execution halts and the
appropriate message is displayed. This is not the case, though, when dumping
to printer.
 
Before printing commences, the current "good" values of parameters are stored
in a memory table. Whenever a single imbedded command (or a block of imbedded
commands in sequence) is executed, the validity of the parameters is
re-checked. If all is okay, the parameters are implemented, and the stored
table of parameters is updated. However, if an error is discovered, no
indication is given; the last-stored table of values is merely reloaded, and
execution continues. This can be confusing if you don't expect it; therefore,
to avoid surprises, it is advisable to dump your document to the screen at
least once before printing it, just to see what (if any) errors ar generated.
 
 
                                  ERROR MESSAGES

The following messages may be displayed upon discovery of bad parameter
values:
 
    "At least 5 characters per line."
         This is generated if LM + PM + 5 is greater than RM. If generated   
during a screen-dump, it usually means you re-defined LM too high            
without lowering PM.
 
    "Bad Slot."
         An attempt was made to assign a value greater than 7 to PD.
 
 
         The following 2 errors can only be generated if the value of PI is  
greater than zero.
 
    "Bad PRINTED LINES value."
         This is generated if PL is less than 3 or greater than the value of 
PI.
 
    "Top Margin too large."
         This rarely happens, but is generated if you are running with a very
low PL. Then, if TM is greater than PL-2, no lines of text would be          
printed, just a Header line and skipped spaces; so, an error is              
generated instead.
 
In addition, the message:
 
    "Invalid file type."
 
will occur if the filetype of the file you are trying to load is not on the
internal look-up table. See CUSTOMIZING, immediately following. 
 
                             CUSTOMIZING FREEPRINTER

FREEPRINTER was designed to be flexible; there are a number of user-
modifications possible. To implement them, all you need do is BLOAD
FREEPRINTER from Applesoft, enter the Monitor with a CALL -151, and make your
changes. Exit back to Applesoft with 3D0G. Once modified, you may execute
FREEPRINTER immediately by issuing a CALL 32768 (you should not use the
Ampersand command to execute the program until this call has been made at
least once.) Should you decided to make your changes permanent, though, the
command BSAVE FREEPRINTER, A$8000, L$FD0 will accomplish this; none of the
modifications will change the length of the program. You might save your
changed program to a different disk, or under a different filename so that
you can have different versions available for your needs.
 
ADDING FILETYPES: Currently only the ID byte for TXT-type files (ID byte
=$04) is stored in the 5-byte look-up table at memory locations $808B-808F.
There is room for 4 more file-types. Merely poke their ID values into the
table, replacing the zeroes starting at $808C. Use up the zeroes in order; a
zero-byte indicates End-of-Table. (The first byte following the
table--$8090--is the low byte of the address of the Main Buffer; as such, it
should always be zero, and will act as End-of-Table if you really use all
five bytes.) 
 
Note: FREEPRINTER was designed to look only at sequential text files; it
assumes a zero-byte in the file indicates the End-of-File, so looking at a
random text file for instance, would be unrewarding at best.
 
SCREEN DUMP SPEED: The default speed of the screen dump that is in effect
when FREEPRINTER is booted is controlled by the value of the byte at $809E;
the byte's current value is $40. If you would like to have a different
default speed, change this byte: the larger the value, the slower the
display.
 
 DEFAULT PARAMETERS: The display parameters you get when you load FREEPRINTER
are stored in a table starting at $80A8. They are as follows:
 
ADDRESS         PARAMETER        CURRENT VALUE
______________________________________________
$80A8           Left Margin           $0
$80A9           Right Margin          $4E  (78 decimal)
$80AA           Paragraph Margin      $0
$80AB           Line Interval         $0
$80AC           Printer Destination   $3
$80AD           Page Interval         $0
$80AE           Printed Lines         $0
$80AF           Top Margin            $0
$80B0           Single Page?          $0
$80B1           Screen Format?        $0
$80B2           Print Mode            $0 (LJ=0, RJ=1, CJ=2, FJ=3)
 
In addition, the value of the first page number printed ($1) is stored at
$80F5; this can be made higher if you are printing a document from the
middle.
 
For your own information, the stored pathname starts at $9001 with a length
byte at $9000, and the Top Line is stored at $9081, with a length byte at
$9080.
 
BUFFER SIZE: FREEPRINTER is supplied to use as much memory as possible, for
this reduces the number of disk-drive reads required; as supplied, its main
file buffer starts at $1000, extending to $7FFF. Another page of memory is
always required preceding the main buffer (here $F00 to $FFF). As mentioned
in the introduction, the size of this pair of buffers is variable. To change
it, merely poke the HIGH BYTE of the first page of your buffer in location
$8091. For example, poking $30 into $8091 will force the main buffer to begin
at $3000, with the preceding 1-page buffer at $2F00. All bytes below $2F00
will be untouched. Because of this feature, the possibility exists of using
FREEPRINTER from within a co-resident Applesoft program. FREEPRINTER can
operate successfully with a main buffer as small as 2 pages (poke $7E into
$8091) leaving locations $800 to $7CFF untouched. A co-resident program under
these circumstances would have available $7500 bytes at most.
 
Note 1: Because of ProDOS' general-purpose file buffer, if your co-resident
program makes any kind of disk access at all, or if you even wish to catalog
a disk from immediate mode, HIMEM must be set $400 bytes lower than the
beginning of the 1-page pre-buffer. (Example: Main buffer starting at $7000:
poke $70 into $8091 (POKE 32913,112). The pre-buffer starts at $6F00; HIMEM
should be set for $6B00 (27392 decimal.) FREEPRINTER sets HIMEM for you,
according to whatever buffer space you have selected, and restores HIMEM to
nominal ($9600) upon exiting with the "&Q" command.
 
Note 2: To use FREEPRINTER from a co-resident Applesoft program, you must
BLOAD FREEPRINTER as its first line. (DO NOT DEFINE ANY STRINGS UNTIL AFTER
FREEPRINTER INITIALIZES ITSELF, specifically Control-D's!)  Immediately after
bloading, poke the high byte of the address of the main buffer (should you
wish to change it) into 32913 ($8091, as explained above). Poke 2 into
location 513 ($201, to inform the program that you wish to exit upon
initialization), and CALL 32768 to do the actual initialization.  To print a
file, You must POKE the letters of the COMPLETE pathname of the file
(including LEADING and TRAILING slashes) in "positive" ASCII into the buffer
at $9001, poking the length of the pathname into $9000. Then poke 1 into 513
($201) to tell the program to skip its routine to get the filename from you,
poke 0 into 36992 ($9080, which performs a minor bit of initialization that
the above poke unfortunately causes to be skipped) and issue an Ampersand.
The following sample code will accomplish this, configuring FREEPRINTER for
its minimum size.
 
          10 PRINT CHR$(4)"BLOAD /VOLUME/FREEPRINTER"
          20 POKE 32913, 126               :  Rem Buffer begins at $7E00.
          30 POKE 513,2                    :  Rem Exit after initialization.
          40 CALL 32768                    :  Rem Initialize program & set
                                              HIMEM.
          Your program goes here. Then, to print a text file:
 
          100 NM$ = "/VOLUME/SUBDIR/MYFILE/"
          110 FOR X = 1 TO  LEN (NM$)
          120 POKE 36864 + X, ASC ( MID$ (NM$,X,1)) : Rem 36864 = $9000
          130 NEXT X
          140 POKE 36864, LEN (NM$)
          150 POKE 513,1                            : Rem   513 = $201
          160 POKE 36992,0                          : Rem 36992 = $9080
          170 &
 
When using this technique, FREEPRINTER is set to skip past all menus and jump
right to the print routine; all non-default parameters should be poked into
place before calling with the ampersand. The routine will exit back to your
program, where you left off.
 
Note that lines 10-40 should only be executed once; repeated attempts to
BLOAD FREEPRINTER will fail, as the bit-map has been marked to show that
memory is occupied in the loading area, and you'll merely generate the
ever-popular NO BUFFERS AVAILABLE error. The exit routine (&Q) will
warm-start ProDOS, and may not be used from within a program, except as the
last line. To use it from within a program, poke 513 with 81 (uppercase "Q")
and issue an ampersand.
 
          500 POKE 513,81
          505 &
 
Note 3: When using FREEPRINTER from within an Applesoft program, all errors
that would result in program termination are directed back into the Applesoft
program, so that normal ONERR GOTO routines will work. For UNTRAPPED errors,
if the generated error is a FREEPRINTER error (as opposed to a ProDOS error),
BASIC.SYSTEM still wants to print one of its own error messages after the
FREEPRINTER error message. So, to avoid confusion caused by two successive
error messages, FREEPRINTER tells BASIC.SYSTEM to display Apple Computer's
copyright notice instead. The error code for any FREEPRINTER-generated error
is 126. ($7E)
 
Note 4: As alluded to above, FREEPRINTER sets the ProDOS Memory Bit-map to
protect itself when loaded. The Bit-map is set during initialization, when
FREEPRINTER is first BRUN. Exiting FREEPRINTER using "&Q" will restore the
Bit-map to its normal configuration. Should you wish FREEPRINTER not to
modify the Bit-map and HIMEM, the following two patches may be used. The
first jumps past the initialization, and the second jumps past the
restoration:
 
   8024:4C BD 80   (replacing 8024:A9 00 A8)
 
   8069:4C 7E 80   (replacing 8046:A9 00 A8)
 
Make these changes only to a COPY of the FREEPRINTER program, not to your
original downloaded version.
 
PAGE BREAKS: As explained above, (when PI is non-zero) FREEPRINTER works
best if your printer is positioned to start at the first line on your first
printed page. This is because lines are skipped at the top of each page to
center the text on the page. It is possible to modify FREEPRINTER to ignore
these skipped lines on the first page of printing, so that you may position
the printer yourself. From the monitor:
 
   8298:EA EA EA
 
   830C:EA EA EA
 
IMBEDDED ESCAPE SEQUENCES: Correct centering and justification is maintained
for imbedded escape sequences consisting of the Escape character and one
non-control character. Because of the wide variety of command structures
required for all the different printers on the market, full support is beyond
the scope of this program. However, if your printer has commands with the
structure of Escape Character followed by two or three non-control
characters, you may modify 6 bytes of code starting at $868A to correct this.
Currently these bytes are NOPs (hex $EA). To permit a second non-control
character, insert (from the Monitor)
 
   868A:CE A3 80
 
For a third character, repeat the sequence at $868D.
 
As mentioned earlier, this program is designed to be flexible. The source
code is rather lengthy, so I've elected not to upload it at the moment. If
you would like to modify FREEPRINTER for your own purposes however, I'd be
happy to make it available. Just drop me an easyplex, or a note on the BB.
 
While the program SHOULD work on any APPLE // that can run ProDOS and display
lower case text, it's only been tested on an enhanced //e with 128k and APPLE
compatible 80 column card. If you have any problems using it on your system,
I'd like to know about it; there could be any number of implementation
details I've overlooked which, if I were aware of, I'd correct.